Content type rationale and tagging by ltagliaferri · Pull Request #2730 · chainguard-dev/edu

ltagliaferri · 2025-11-03T20:10:07Z

This introduces content types in the metadata so we can better organize content. It also has scripts for working with the content locally and READMEs for contributors.

Signed-off-by: ltagliaferri <[email protected]>

netlify · 2025-11-03T20:10:15Z

✅ Deploy Preview for ornate-narwhal-088216 ready!

Name	Link
🔨 Latest commit	`7149520`
🔍 Latest deploy log	https://app.netlify.com/projects/ornate-narwhal-088216/deploys/690ab7d4e2f1160008854e35
😎 Deploy Preview	https://deploy-preview-2730--ornate-narwhal-088216.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify project configuration.

SharpRake

A few questions/issues:

I'd like to see a mention of this made in the Style Guide's Front matter section. Even if it's just pointing to the README.md file, I'd like to make sure this is flagged there.
I'm not clear on when one contentType applies vs another. I think this mostly has to do with the fact that it feels like we're dealing with two different kinds of categories: conceptual, tutorial, and how-to-guide all feel distinct, but product-docs and integration feel like umbrella categories for the others. Like, most docs I'd label as integrations could be how-to-guides, and most product-docs are one of the three.

I only got about halfway through these (to content/chainguard/chainguard-images/staying-secure/updating-images/renovate/index.md [for my own reference]) but I'd like to make sure we're set on these categories and get clear the logic for when they apply before going further.

SharpRake · 2025-11-03T21:02:04Z

content/chainguard/administration/terraform-provider/index.md

    parent: "administration"
 toc: true
 weight: 008
+contentType: "tutorial"


I'm unclear on when something is a product doc vs a tutorial (or something else). I think this is the first tutorial I've seen but I think it could go either way here.

SharpRake · 2025-11-03T21:03:23Z

content/chainguard/chainctl-usage/comparing-chainctl-to-console/index.md

    parent: "chainctl-usage"
 weight: 025
 toc: true
+contentType: "conceptual"


Again, unclear on when product-doc is applicable or not. It almost feels too broad to be useful.

SharpRake · 2025-11-03T21:04:15Z

content/chainguard/chainctl-usage/how-to-install-chainctl.md

    parent: "administration"
 toc: true
 weight: 010
+contentType: "how-to-guide"


For that matter, I'm not clear on when something is a tutorial vs. a how-to-guide.

just double checked the README, learning-oriented vs. task-oriented makes sense but it still feels a bit fuzzy

tutorial is more for introducing someone to something vs. how-to which is giving someone who know the general route a more detailed map

SharpRake · 2025-11-03T21:07:43Z

...guard-images/chainguard-registry/pull-through-guides/artifact-registry-pull-through/index.md

    parent: "pull-through-guides"
 toc: true
 weight: 005
+contentType: "product-docs"


IMO all the pull-through guides make more sense as how-to-guides

or integration, perhaps

I guess this is more of a question of whether you think it should sit with the product docs or not. I think I would lump integrations and product docs together for now

Suggested change

contentType: "product-docs"

contentType: "integration"

SharpRake · 2025-11-03T21:17:21Z

content/chainguard/chainguard-images/staying-secure/fedramp-considerations/index.md

    parent: "features"
 weight: 007
 toc: true
+contentType: "product-docs"


I'd call this one conceptual

SharpRake · 2025-11-03T21:17:47Z

content/chainguard/chainguard-images/staying-secure/security-advisories/how-to-use/index.md

    parent: "chainguard-images"
 weight: 010
 toc: true
+contentType: "how-to-guide"


I'd call this one a tutorial

SharpRake

Second review, some more thoughts:

I'm a little wary of cases where all the docs in one bucket are the same contentType. For example, each Libraries doc is a product-doc, and each migration doc is a how-to
FAQs should be conceptual, most are listed as how-tos

SharpRake · 2025-11-04T01:15:49Z

...d/chainguard-images/staying-secure/updating-images/strategies-tools-updating-images/index.md

    parent: "chainguard-images"
 weight: 015
 toc: true
+contentType: "how-to-guide"


Suggested change

contentType: "how-to-guide"

contentType: "tutorial"

content/chainguard/chainguard-images/staying-secure/working-with-scanners/false-results.md

content/chainguard/chainguard-images/troubleshooting/_index.md

SharpRake · 2025-11-04T01:17:53Z

content/chainguard/chainguard-images/vuln-comparison/_index.md

  },
 ]

+contentType: "conceptual"


IMO all the vuln-comparison docs should be product-docs

I am thinking we should get rid of them but I need to check with some other stakeholders on that.

SharpRake · 2025-11-04T01:21:13Z

content/chainguard/libraries/cve-remediation.md

@@ -12,6 +12,7 @@ menu:
    parent: "libraries"
 weight: 005
 toc: true
+contentType: "product-docs"


Suggested change

contentType: "product-docs"

contentType: "conceptual"

SharpRake · 2025-11-04T01:21:35Z

content/chainguard/libraries/verification.md

@@ -14,6 +14,7 @@ menu:
    parent: "libraries"
 weight: 004
 toc: true
+contentType: "product-docs"


Suggested change

contentType: "product-docs"

contentType: "tutorial"

SharpRake · 2025-11-04T01:24:30Z

content/open-source/build-tools/_index.md

@@ -7,6 +7,7 @@ lastmod: 2024-05-02T08:49:15+00:00
 draft: false
 images: []
 weight: 20
+contentType: "how-to-guide"


I feel like the index pages sit outside of the contentTypes

content/open-source/build-tools/apko/faq.md

content/open-source/build-tools/apko/troubleshooting.md

content/open-source/build-tools/melange/faq.md

SharpRake

third review (hit submit too early). Approving! LMK if you have any questions

content/open-source/build-tools/melange/overview/index.md

SharpRake · 2025-11-04T01:31:59Z

content/software-security/learning-labs/_index.md

@@ -9,6 +9,7 @@ images: []
 tags: ["Learning Labs", "Overview"]
 toc: true
 hidepageslist: true
+contentType: "conceptual"


I think all the learning labs types could use more thought, most are more hands on than conceptual, no?

SharpRake · 2025-11-04T01:33:21Z

docs/CONTENT_TYPE_GUIDE.md

@@ -0,0 +1,275 @@
+# Content Type Taxonomy Guide


I should have read this first, this is very helpful 🙃

SharpRake · 2025-11-04T01:34:39Z

docs/CONTENT_TYPE_GUIDE.md

+| **integration** | "How do I use X with Y?" | "Using Chainguard Images with GitHub Actions" |
+| **conceptual** | "What is this?" | "What is an SBOM?" |
+
+## Examples by Directory


double check that these examples align with the final state after you make changes (if you make any at all)

…th-scanners/false-results.md Co-authored-by: Mark Drake <[email protected]> Signed-off-by: ltagliaferri <[email protected]>

Co-authored-by: Mark Drake <[email protected]> Signed-off-by: ltagliaferri <[email protected]>

ltagliaferri · 2025-11-05T02:07:22Z

content/chainguard/administration/terraform-provider/index.md

    parent: "administration"
 toc: true
 weight: 008
+contentType: "tutorial"


Suggested change

contentType: "tutorial"

contentType: "product-docs"

ltagliaferri · 2025-11-05T02:07:46Z

content/chainguard/chainctl-usage/comparing-chainctl-to-console/index.md

    parent: "chainctl-usage"
 weight: 025
 toc: true
+contentType: "conceptual"


Suggested change

contentType: "conceptual"

contentType: "product-docs"

ltagliaferri · 2025-11-05T02:09:16Z

content/chainguard/chainctl-usage/how-to-install-chainctl.md

    parent: "administration"
 toc: true
 weight: 010
+contentType: "how-to-guide"


tutorial is more for introducing someone to something vs. how-to which is giving someone who know the general route a more detailed map

ltagliaferri · 2025-11-05T02:14:00Z

...guard-images/chainguard-registry/pull-through-guides/artifact-registry-pull-through/index.md

    parent: "pull-through-guides"
 toc: true
 weight: 005
+contentType: "product-docs"


I guess this is more of a question of whether you think it should sit with the product docs or not. I think I would lump integrations and product docs together for now

Suggested change

contentType: "product-docs"

contentType: "integration"

ltagliaferri · 2025-11-05T02:15:13Z

content/chainguard/chainguard-images/vuln-comparison/_index.md

  },
 ]

+contentType: "conceptual"


I am thinking we should get rid of them but I need to check with some other stakeholders on that.

Co-authored-by: Mark Drake <[email protected]> Signed-off-by: ltagliaferri <[email protected]>

Content type rationale and tagging

a3fd3f7

Signed-off-by: ltagliaferri <[email protected]>

ltagliaferri requested a review from a team as a code owner November 3, 2025 20:10

SharpRake reviewed Nov 3, 2025

View reviewed changes

SharpRake reviewed Nov 4, 2025

View reviewed changes

SharpRake approved these changes Nov 4, 2025

View reviewed changes

ltagliaferri and others added 4 commits November 4, 2025 21:10

Update content/chainguard/chainguard-images/staying-secure/working-wi…

f337f0f

…th-scanners/false-results.md Co-authored-by: Mark Drake <[email protected]> Signed-off-by: ltagliaferri <[email protected]>

Update content/open-source/build-tools/apko/troubleshooting.md

360c195

Co-authored-by: Mark Drake <[email protected]> Signed-off-by: ltagliaferri <[email protected]>

Apply suggestion from @SharpRake

b149dd4

Co-authored-by: Mark Drake <[email protected]> Signed-off-by: ltagliaferri <[email protected]>

Apply suggestion from @SharpRake

e3791fe

Co-authored-by: Mark Drake <[email protected]> Signed-off-by: ltagliaferri <[email protected]>

ltagliaferri commented Nov 5, 2025

View reviewed changes

ltagliaferri and others added 2 commits November 4, 2025 21:34

Update content/open-source/build-tools/melange/overview/index.md

71775fa

Co-authored-by: Mark Drake <[email protected]> Signed-off-by: ltagliaferri <[email protected]>

Update content/open-source/build-tools/apko/faq.md

7149520

Co-authored-by: Mark Drake <[email protected]> Signed-off-by: ltagliaferri <[email protected]>

Conversation

ltagliaferri commented Nov 3, 2025

Uh oh!

netlify bot commented Nov 3, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Deploy Preview for ornate-narwhal-088216 ready!

Uh oh!

SharpRake left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

SharpRake left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

SharpRake left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

netlify bot commented Nov 3, 2025 •

edited

Loading